Programmer Power Tools/Programmer Power Tools.iso/asmutl/usoftpd.arc/MACRO.DOC

Text File | 1987-07-31 | 18KB | 661 lines

         Calling Macros in DOS.INC and BIOS.INC

You are    responsible for    saving and restoring registers used in
macros.    The "Registers used" field identifies registers    to save.

Macros that accept address parameters use internal macros that
allow you to specify addresses in several ways.    The macro
automatically identifies the type of the argument and handles it
appropriately. For example, assume the following declarations:

  String    DB     "test$"
  pString   DW     Str
  fpString  DD     Str

Given these values, the    macro @DispStr (which displays the string
at DS:DX) has the following effects:

  Kind of argument        Example          Value    loaded

  Label    of byte    variable    @DispStr String      DS:OFFSET String
  Near pointer variable        @DispStr pString      DS:pString
  Far pointer variable        @DispStr fpString      fpString[2]:fpString[0]
  Constant            @DispStr 0          DS:0
  Pointer in register        @DispStr si          DS:SI
  Near Pointer with segment @DispStr pString,es      ES:pString
  Constant with    segment        @DispStr 0,es      ES:0
  Register with    segment        @DispStr di,es      ES:DI

Note that if a far pointer or a    segment    is given, DS must be
saved before the macro call and    restored afterward. Segments may
be given as registers, constants, or word variables.

In syntax, parameters enclosed in brackets are optional.
Paramaters sometimes have a leading symbol to indicate that the
argument must have a certain type, as shown below:

  Leading Symbol   Example    Limitation

    #       #return    Must be    constant
    &       &vector    Must be    offset address as described above
    $       $terminator    May be constant    or register, but not memory

Parameters with    no leading symbol may be constants, registers, or
variables. Parameters are 16-bit except    where noted in the description.

Symbols    must be    previously defined before they can be passed as
arguments to most of the DOS macros. Generally this means that
data must be declared before code in the source    file.

          DOS Macro Syntax and Description

KEYBOARD INPUT

@GetKey    (01h, 07h, 08h,    0Ch)

Gets a keystroke from the keyboard

Syntax:        @GetKey    [#echo]    [,[#break] [,#clearbuf]]

Arguments:    echo        = nonzero to echo keystroke    - default yes
        break        = nonzero to accept    Control-C - default yes
        clearbuf    = nonzero to clear keyboard    buffer - default no
        (Arguments may be omitted to get defaults)
Return:        ASCII code of key in AL
Registers used:    AX used    for all, DL used if echo on and    ctrl-c off


@GetStr    (0Ah)

Gets a string from the keyboard

Syntax:        @GetStr    &buffer    [,[$terminator]    [,[#limit] [,segment]]]

Arguments:    buffer        = Offset of    buffer where string will be stored
            Byte 1  = Maximum length of    string (before call)
            Byte 2  = Actual length of string (after call)
            Byte 3+ = Bytes of string
        terminator  = Terminating byte - usually null (0) or $ (24h)
        limit        = Maximum length of    string (if not given as
                  argument,    must be    in buffer before macro call)
        segment        = Segment of buffer    (DS if not given)
Return:        Pointer    to string in SI, length    of string in BX
Registers used:    AX, DX,    BX, SI

OUTPUT

@DispCh    (02h)

Displays one or    more characters    to screen

Syntax:        @DispCh    char [,char]...

Arguments:    char        = 8-bit ASCII code
Return:        Code in    AL
Registers used:    AX and DL


@PrtCh (05h)

Prints one or more characters to LPT1

Syntax:        @PrtCh char [,char]...

Arguments:    char        = 8-bit ASCII code
Return:        Code in    AL
Registers used:    AX and DL


@DispStr (09h)

Displays a $-terminated    string

Syntax:        @DispStr &address [,segment]

Arguments:    address        = Address of string    terminated by "$" (24h)
        segment        = Segment of address string    (DS if not given)
Return:        None
Registers used:    AX and DS

DEVICE I/O

@Read (3Fh)

Reads data from    a file or device

Syntax:        @Read &buffer, length [,[handle] [,segment]]

Arguments:    buffer        = Offset of    buffer where data will be stored
        length        = Length of    data in    bytes
        handle        = File or device handle; if    none given,
                  keyboard (handle 0) is assumed
        segment        = Segment of address string    (DS if not given)
Return:        If carry clear,    bytes read in AX
Registers used:    Always AX, DX, BX, and CX; DS if segment changed


@Write (40h)

Writes data to a file or device

Syntax:        @Write &buffer,    length,    [,[handle] [,segment]]

Arguments:    buffer        = Offset of    buffer where data is stored
        length        = Length of    data in    bytes
        handle        = File or device handle; if    none given, screen
                  (handle 1) is assumed
        segment        = Segment of address string    (DS if not given)
Return:        If carry clear,    bytes written in AX
Registers used:    Always AX, DX, BX, and CX; DS if segment changed

FILE CONTROL

@MakeFil (3Ch, 5Ah, 5Bh)

Creates    a file

Syntax:        @MakeFil &path [,[attrib] [,[segment] [,#kind]]]

Arguments:    path        = ASCIIZ string of file
        attrib        = File atrribute (0    is default if none given)
        segment        = Segment of address string    (DS if not given)
        kind        = If none given, a file is always created even if
                  one already exists. Under    DOS 3+ "tmp" can be
                  given to create a    unique file or "new" to    create
                  file only    if one doesn't already exist.
Return:        If carrry clear, file handle in    AX
Registers used:    Always AX, DX, and CX; DS if segment changed


@OpenFil (3Dh)

Opens a    file for input or output

Syntax:        @OpenFil &path,    #access    [,segment]

Arguments:    path        = ASCIIZ string of file
        access        = File access code
        segment        = Segment of address string    (DS if not given)
Return:        If carrry set, error code in AX
Registers used:    Always AX and DX; DS if    segment    changed


@ClosFil (3Eh)

Closes an open file handle

Syntax:        @ClosFil handle

Arguments:    handle        = Previously opened    file handle
Return:        If carrry set, error code in AX
Registers used:    AX and BX


@DelFil    (41h)

Deletes    a specified file

Syntax:        @DelFil    &path [,segment]

Arguments:    path        = Offset of    ASCIIZ filespec
        segment        = Segment of path (DS if none given)
Return:        If carrry set, error code in AX
Registers used:    AX and DX; DS if segment changed

@MoveFil (56h)

Moves or renames a file    by changing its    path specification.

Syntax:        @MoveFil &old, &new [,[segold] [,segnew]]

Arguments:    old        = Offset of    file spec to be    renamed
        new        = Offset of    new file spec
        segold        = Segment of old name (DS if none given)
        segnew        = Segment of new name (ES if none given)
Return:        If carry set, error code in AX
Registers used:    AX, DX,    and DI;    DS and ES if corresponding segments changed


@GetFirst (4Eh)    and @GetNext (4Fh)

Parses file specifications (optionally including wild cards) into
file names

Syntax:        @GetFirst &path    [,[attribute] [,segment]]
        @GetNext

Arguments:    path        = Offset of    ASCIIZ filespec    (can have wild cards)
        attribute   = File attribute to    search for (0 for normal if
                  none given)
        segment        = Segment of path (DS if none given)
Return:        If carrry set, error code in AX
Registers used:    @GetFirst   = AX, CX, and DX; DS if segment changed
        @GetNext    = AX only


@GetDTA    (1Ah) and @SetDTA (2Fh)

Gets or    sets the Disk Transfer Address (DTA)

Syntax:        @GetDTA
        @SetDTA    &buffer    [,segment]

Arguments:    buffer        = Offset of    new DTA    buffer
        segment        = Segment of new DTA buffer    (DS if none given)
Return:        @GetDTA        = ES:BX points to DTA
        @SetDTA        = None
Registers used:    AX for both; DS    and DX for @SetDTA; ES and BX for @GetDTA

@GetFilSz (42h)

Gets the file size by moving the file pointer to end of    the file.
Note that the file pointer is reset to zero. Thus this macro should
not be called during operations    that move the pointer.

Syntax:        @GetFilSz handle

Arguments:    handle        = Previously opened    file handle
Return:        If carrry clear, file length in    DX:AX
Registers used:    AX, BX,    CX, and    DX


@MovePrtAbs and    @MovePtrRel (42h)

Moves the file pointer in an open file.    The pointer can    be moved to
an absolute position, or relative to its current position.

Syntax:        @MovePrtAbs handle [,distance]
        @MovePrtRel handle [,distance]

Arguments:    handle        = Previously opened    file handle
        distance    = Distance to move pointer - must be a 16-bit
                  constant or a 16-    or 32-bit variable; or
                  leave blank and set distance in CX:DX before
                  macro call
Return:        If carrry clear, file pointer position in DX:AX
Registers used:    AX, BX,    CX, and    DX

DIRECTORY CONTROL

@MkDir,    (39h), @RmDir (3Ah), and @ChDir    (3Bh)

Creates, deletes, or changes to    the specified directory

Syntax:        @MkDir &path [,segment]
        @RmDir &path [,segment]
        @ChDir &path [,segment]

Arguments:    path        = Offset of    ASCIIZ string to
        segment        = Segment of path (DS if none given)
Return:        If carrry set, error code in AX
Registers used:    AX and DX; DS if segment changed


@GetDir    (47h)

Returns    the current directory of the specified drive

Syntax:        @GetDir    &path [,[drive]    [,segment]]

Arguments:    buffer        = Offset of    buffer to receive ASCIIZ directory
        drive        = 8-bit drive number - 0=current, 1=A, 2=B,    etc.
                  (0 if none given)
        segment        = Segment of path (DS if none given)
Return:        If carrry set, error code in AX
Registers used:    AX, SI,    and DL;    DS if segment changes


DRIVE CONTROL

@GetDrv    (0Eh) and @SetDrv (19h)

Gets or    sets the current drive

Syntax:        @GetDrv
        @SetDrv    drive

Argument:    drive        = 8-bit drive number (0=A, 1=B, etc.)
Return:        @GetDrv        = Drive number in AL (0=A, 1=B, etc.)
        @SetDrv        = Number of    drives in AL
Registers used:    AX for both; DL    for @SetDrv


@ChkDrv    (36h)

Gets various data about    a disk

Syntax:        @ChkDrv    [drive]

Argument:    drive        = 8-bit drive number (0=current,A=1, B=2, etc.);
                  if none given, current assumed
Return:        AX        = Sectors per cluster (-1 if drive invalid)
        BX        = Available    clusters
        CX        = Bytes per    sector
        DX        = Clusters per drive
Registers used:    AX, BX,    CX, and    DX

PROCESS    CONTROL

@Exit (4Ch)

Exits to DOS with return code

Syntax:        @Exit [#return]

Argument:    return        = 8-bit code to return to DOS; if none given,
                  AL is used
Return:        None
Registers used:    AX


@Exec (4Bh)

Executes a child process or an overlay

Syntax:        @Exec path, params [,[segpath] [,[segparams] [,overlay]]]

Arguments:    path        = Offset of    ASCIIZ filespec    to be executed
        params        = Offset of    process    parameter block
        segpath        = Segment of filespec (DS if none given)
        segparams   = Segment of parameter block (ES if    none given)
        overlay        = If not defined, normal process executed;
                  if defined, overlay executed
Return:        If carry set, error code
Registers used:    AX, SI,    and DI;    DS and ES if corresponding segments given


@GetRet    (4Dh)

Gets the return    code of    a child    process

Syntax:        @GetRet

Argument:    None
Return:        Return code in AX
Register used:    AX


@TSR (31h)

Terminates a program, but leaves it resident in    memory

Syntax:        @TSR paragraphs    [,#return]

Arguments:    return        = Code to return to    DOS; if    none, AL used
        paragraphs  = Memory in    paragraphs (16 bytes) to
                  allocate for resident program
Return:        None
Registers used:    AX and DX

MEMORY CONTROL

@FreeBlok (49h)

Frees a    block of memory

Syntax:        @FreeBlok [segment]

Argument:    segment        = Starting address of memory to be freed;
                  if none, ES address assumed
Return:        If carry set, error code in AX
Register used:    AX; ES if segment given


@GetBlok (48h)

Allocates a block of memory

Syntax:        @GetBlok paragraphs

Argument:    paragraphs  = Paragraphs (16 bytes) of memory wanted
Return:        AX and ES   = Segment address of allocated memory
        BX        = Paragraphs actually allocated (may be
                  less than    requested if memory is short)
Register used:    AX and BX


@ModBlok (48h)

Modifies an allocated block of memory

Syntax:        @ModBlok paragraphs [,segment]

Argument:    paragraphs  = Paragraphs (16 bytes) of memory wanted
        segment        = Starting address of memory to be freed;
                  if none, ES address assumed
Return:        If carry set, error code in AX,    else:
            ES  = Segment address of allocated memory
            BX  = If carry is clear, paragraphs allocated
Register used:    AX and BX; ES if segment given

MISCELLANEOUS

@GetDate (2Ah) and @SetDate (2Bh)

Gets or    sets the system    date

Syntax:        @GetDate
        @SetDate month,    day, year

Arguments:    year        = 16-bit year (1980-2099)
        month        = 8-bit month (1-12)
        day        = 8-bit day    (1-31)
Return:        For @GetDate:
            AL  = Day of week (0 = Sunday, 1 = Monday, etc.)
            CX  = Year (1980-2099)
            DL  = Month (1-12)
            DH  = Day (1-31)
        For @SetDate:
            AL  = If date was valid    0, else    -1
Registers used:    AX, CX,    and DX


@GetTime (2Ch) and @SetTime (2Dh)

Gets or    sets the system    time

Syntax:        @GetTime
        @SetTime hour,minute,second,hundredth

Arguments:    hour        = 8-bit hour (0-23)
        minute        = 8-bit hour (0-59)
        second        = 8-bit hour (0-59)
        hundredth   = 8-bit hour (0-99)
Return:        For @GetTime:
            CL  = Hour (0-23)
            CH  = Minute (0-59)
            DL  = Second (0-59)
            DH  = Hundredth    (0-99)
        For @SetTime:
            AL  = If time was valid    0, else    -1
Registers used:    AX, CX,    and DX


@GetVer    (30h)

Gets the DOS version

Syntax:        @GetVer

Argument:    None
Return:        AL        = Major version (0 for versions prior to 2.0)
        AH        = Minor version
        BH        = OEM serial number
        BL:CX        = 24-bit user number
Register used:    AX, BX,    and CX

@GetInt    (35h) and @SetInt (25h)

Gets or    sets the vector    for a specified    interrupt routine

Syntax:        @GetInt    #interrupt
        @SetInt    #interrupt, &vector [,segment]

Arguments:    interrupt   = 8-bit interrupt number
        vector        = Offset of    interrupt routine
        segment        = Segment of routine - if none given, DS assumed
                  for data;    segment    ignored    for code labels
Return:        @GetInt        = None
        @SetInt        = ES:BX points to interrupt    routine
Registers used:    AX for both; ES    and BX for @GetInt; DS and DS for @SetInt

         BIOS Macro Syntax and Description


MODE, PAGE, AND    COLOR CONTROL

@GetMode (I 10h    F 0Fh)

Gets the current video mode and    page

Syntax:        @GetMode

Arguments:    None
Return:        AL        = Mode
        AH        = Width in characters
        BH        = Page
Registers used:    AX and BH


@SetMode (I 10h    F 00h)

Gets the current video mode and    page

Syntax:        @SetMode mode

Arguments:    mode        = 8-bit video mode
Return:        none
Registers used:    AX


@SetColor (I 10h F 0Bh)

Sets the background color

Syntax:        @SetColor color

Arguments:    color        = 8-bit background color (0-15);
                  border color in text modes
Return:        none
Registers used:    AX and BX


@SetPalet (I 10h F 0Bh)

Sets the color palette

Syntax:        @SetPalet color

Arguments:    color        = 8-bit color palette (0-1 for modes 5 and 6)
Return:        none
Registers used:    AX and BX

@SetPage (I 10h    F 05h)

Sets the video page

Syntax:        @SetPage page

Arguments:    page        = 8-bit page number; 0-3 for modes 2 and 3
Return:        none
Registers used:    AX


CHARACTER AND CURSOR CONTROL

@GetCur    (I 10h F 04h)

Gets the cursor    position and size

Syntax:        @GetCur    [page]

Arguments:    page        = 8-bit page with cursor (if none, 0 assumed)
Return:        DL        = Column
        DH        = Row
        CL        = Starting scan line
        CH        = Ending scan line
Registers used:    AX, DX,    CX, and    BH


@SetCurPos (I 10h F 02h)

Sets the cursor    position

Syntax:        @SetCurSz [column] [,[row] [,page]]

Arguments:    column        = 8-bit column; if none, DL    used
        row        = 8-bit row; if none, DH used
        page        = 8-bit page with cursor (if none, 0 assumed)
Return:        none
Registers used:    AX, DX,    and BH


@SetCurSz (I 10h F 01h)

Sets the cursor    size and shape by specifying active scan lines.    The
CGA adapter the    lines are 0-7. The monochrome adapter has lines    0-13.

Syntax:        @SetCurSz startline, endline

Arguments:    startline   = 8-bit starting scan line (default    CGA=6; MA=12)
        endline        = 8-bit ending scan    line (default CGA=7; MA=13)
Return:        none
Registers used:    AX and CX

@GetChAtr (I 10h F 08h)

Gets the character and attribute at the    cursor location

Syntax:        @GetChAtr [page]

Arguments:    page        = 8-bit page to check (if none, 0 assumed)
Return:        AH        = Attribute
        AL        = ASCII character
Registers used:    AX and BH


@PutChAtr (I 10h F 09h)    and @PutCh (I 10h F 0Ah)

Puts one or more characters and    attributes at the current cursor
position. For @PutCh, the current attribute is used in text modes
and any    specified attribute is ignored.

Syntax:        @PutChAtr [character] [,[attrib] [,[page] [,count]]]

Arguments:    character   = 8-bit ASCII character to put; if none, AL    used
        attrib        = 8-bit attribute to put; if none, BL used
        page        = 8-bit page to put    on (if none, 0 assumed)
        count        = Number to    put (if    none, 1    assumed)
Return:        AH        = Attribute
        AL        = ASCII character
Registers used:    AX, BX,    CX


@Scroll    (I 10h F 06h and 07h)

Scrolls    a specified window up or down

Syntax:        @Scroll    dist [,[attr] [,[uprow [,[upcol    [,[dnrow] [,dncol]]]]]

Arguments:    dist        = 8-bit number of lines to scroll; positive
                  scrolls down; negative scrolls up; 0 clears
        attr        = 8-bit attribute for blank    lines (if none,    07h)
        uprow        = Upper left row (if none, CH used)
        upcol        = Upper left column    (if none, CL used)
        dnrow        = Lower right row (if none,    DH used)
        dncol        = Lower right column (if none, DL used)
Return:        none
Registers used:    AX, CX,    DX, and    BH


@Cls (I    10h F 06, 08h, and 02h)

Clears the screen of the current page

Syntax:        @Cls

Arguments:    None
Return:        None
Registers used:    AX, BX,    CX, and    DX